﻿<h1>Code Packages and Package Imports</h1>

<p>
Like many modern programming languages,
Go code is also organized as code packages.
To use the exported resources (functions, types, variables and named constants,
etc) in a specified package, the package must first be imported,
except the <code>builtin</code> standard code package.
This article will explain code packages and package imports in Go.
</p>

<a class="anchor" id="import"></a>
<h3>Introduction of Package Import</h3>

<div>
Let's view a small program which imports a standard code package.
(Assume the source code of this program is stored in a file named <code>simple-import-demo.go</code>.)

<pre class="line-numbers must-line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	fmt.Println("Go has", 25, "keywords.")
}
</code></pre>

Some explanations:
<ul>
<li>
	The first line specifies the name of the package containing the source file <code>simple-import-demo.go</code>.
	The <code>main</code> entry function of a program must be put in a package named <code>main</code>.
</li>
<li>
	The third line imports the <code>fmt</code> standard package by using the <code>import</code> is a keyword.
	The identifier <code>fmt</code> is the package name.
	It is also used as the import name of, and represents, this standard package in the scope of containing source file.
	(Import names will be explained a below section.)
	There are many format functions declared in this standard package for other packages to use.
	The <code>Println</code> function is one of them.
	It will print the string representations of
	an arbitrary number of arguments to the standard output.
</li>
<li>
	The sixth line calls the <code>Println</code> function.
	Note that the function name is prefixed with a <code>fmt.</code> in the call,
	where <code>fmt</code> is the name of the package which contains the called function.
	The form <code>aImportName.AnExportedIdentifier</code> is called a
	<a href="https://golang.org/ref/spec#Qualified_identifiers">qualified identifier</a>.
	<code>AnExportedIdentifier</code> is called an unqualified identifier.
</li>
<li>
	A <code>fmt.Println</code> function call has no requirements
	for its arguments, so in this program, its three arguments
	will be deduced as values of their respective default types,
	<code>string</code>, <code>int</code> and <code>string</code>.
</li>
<li>
	For each <code>fmt.Println</code> call,
	a space character is inserted between
	each two consecutive string representations
	and a newline character is printed at the end.
</li>
</ul>

Running this program, you will get the following output:
<pre class="output"><code>$ go run simple-import-demo.go
Go has 25 keywords.
</code></pre>

<p>
Please note, only exported resources in a package can be used
in the source file which imports the package.
Exported resources are the resources whose names are
<a href="keywords-and-identifiers.html#identifier">exported identifiers</a>.
For example, the first character of the identifier <code>Println</code>
is an upper case letter (so the <code>Println</code> function is exported),
which is why the <code>Println</code> function
declared in the <code>fmt</code> standard package can be used
in the above example program.
</p>

<p>
The built-in functions, <code>print</code> and <code>println</code>,
have similar functionalities as the corresponding functions in the
<code>fmt</code> standard package.
Built-in functions can be used without importing any packages.
</p>

<p>
Note, the two built-in functions, <code>print</code> and <code>println</code>,
are not recommended to be used in the production environment,
for they are not guaranteed to stay in the future Go versions.
</p>

<p>
All standard packages are listed <a href="https://golang.org/pkg/">here</a>.
We can also <a href="go-sdk.html#doc">run a local server</a>
to view Go documentation.
</p>

<p>
A package import is also called an import declaration formally in Go.
An import declaration is only visible to the source file which contains the import declaration.
It is not visible to other source files in the same package.
</p>

Let's view another example:
<pre class="line-numbers"><code class="language-go">package main

import "fmt"
import "math/rand"

func main() {
	fmt.Printf("Next random number is %v.\n", rand.Uint32())
}
</code></pre>

<p>
This example imports one more standard package, the <code>math/rand</code> package,
which is a sub-package of the <code>math</code> standard package.
This package provides some functions to produce pseudo-random numbers.
</p>

Some explanations:
<ul>
<li>
	In this example, the package name <code>rand</code> is used as the import name
	of the imported <code>math/rand</code> standard package.
	A <code>rand.Uint32()</code> call will return
	a random <code>uint32</code> integer number.
</li>
<li>
	<code>Printf</code> is another commonly used function
	in the <code>fmt</code> standard package.
	A call to the <code>Printf</code> function must take at least one argument.
	The first argument of a <code>Printf</code> function call must be a <code>string</code> value,
	which specifies the format of the printed result.
	The <code>%v</code> in the first argument is called a format verb,
	it will be replaced with the string representation of the second argument.
	As we have learned in the article
	<a href="basic-types-and-value-literals.html">basic types and their
	literals</a>, the <code>\n</code> in a double-quoted
	string literal will be escaped as a newline character.
</li>
</ul>

The above program will always output:
<pre class="output"><code>Next pseudo-random number is always 2596996162.
</code></pre>

<p>
If we expect the above program to produce a different random number at each run,
we should set a different seed by calling the <code>rand.Seed</code> function
when the program just starts.
</p>

<p>
If multiple packages are imported into a source file,
we can group them in one import declaration by enclosing
them in a <code>()</code>.
</p>

Example:
<pre class="line-numbers"><code class="language-go">package main

// Multiple packages can be imported together.
import (
	"fmt"
	"math/rand"
	"time"
)

func main() {
	 // Set the random seed.
	rand.Seed(time.Now().UnixNano())
	fmt.Printf("Next random number is %v.\n", rand.Uint32())
}
</code></pre>

Some explanations:
<ul>
<li>
	this example imports one more package,
	the <code>time</code> standard package,
	which provides many time related utilities.
</li>
<li>
	function <code>time.Now()</code> returns the current time,
	as a value of type <code>time.Time</code>.
</li>
<li>
	<code>UnixNano</code> is a method of the <code>time.Time</code> type.
	The method call <code>aTime.UnixNano()</code> returns the number of nanoseconds
	elapsed since January 1, 1970 UTC to the time denoted by <code>aTime</code>.
	The return result is a value of type <code>int64</code>,
	which is the parameter type of the <code>rand.Seed</code> function.
	Methods are special functions. We can learn methods in the article
	<a href="method.html">methods in Go</a> for details later.
</li>
</ul>

</div>

<h3>More About <code>fmt.Printf</code> Format Verbs</h3>

<p>
As the above has mentioned, if there is one format verb in the first argument
of a <code>fmt.Printf</code> call, it will be replaced with the string
representation of the second argument.
In fact, there can be multiple format verbs in the first <code>string</code>
argument. The second format verb will be replaced with the string representation
of the third argument, and so on.
</p>

<div>
In Go 101, only the following listed format verbs will be used.
<ul>
<li>
	<code>%v</code>, which will be replaced with the general string representation of the corresponding argument.
</li>
<li>
	<code>%T</code>, which will be replaced with the type name or type literal of the corresponding argument.
</li>
<li>
	<code>%x</code>, which will be replaced with the hex string representation of the corresponding argument.
	Note, the hex string representations for values of some kinds of types are not defined.
	Generally, the corresponding arguments of <code>%x</code> should be integers,
	integer arrays or integer slices (arrays and slices will be explained in a later article).
</li>
<li>
	<code>%s</code>, which will be replaced with the string representation of the corresponding argument.
	The corresponding argument should be a string or byte slice.
</li>
<li>
	Format verb <code>%%</code> represents a percent sign.
</li>
</ul>

An example:
<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	a, b := 123, "Go"
	fmt.Printf("a == %v == 0x%x, b == %s\n", a, a, b)
	fmt.Printf("type of a: %T, type of b: %T\n", a, b)
	fmt.Printf("1%% 50%% 99%%\n")
}
</code></pre>

Output:
<pre class="output"><code>a == 123 == 0x7b, b == Go
type of a: int, type of b: string
1% 50% 99%
</code></pre>

<p>
</p>

<p>
For more <code>Printf</code> format verbs, please read
the online <a href="https://golang.org/pkg/fmt/"><code>fmt</code> package documentation</a>,
or view the same documentation by running a local documentation server.
We can also run <code>go doc fmt</code> to view the documentation of the <code>fmt</code> standard package,
and run <code>go doc fmt.Printf</code> to view the documentation of the <code>fmt.Printf</code> function,
in a terminal.
</p>
</div>

<a class="anchor" id="package"></a>
<h3>Package Folder, Package Import Path and Package Dependencies</h3>

<div>
<p>
A code package may consist of several source files.
These source files are located in the same folder.
The source files in a folder (not including subfolders) must belong to the same package.
So, a folder corresponds to a code package, and vice versa.
The folder containing the source files of a code package is called the folder of the package.
</p>

<p>
For the official Go SDK, a package whose import path containing an <code>internal</code> folder name
is viewed as a special package. It can only be imported by the packages rooted as the direct parent
directory of the <code>internal</code> folder.
For example, package <code>.../a/b/c/internal/d/e/f</code> and <code>.../a/b/c/internal</code>
can only be imported by the packages whose import paths have a <code>.../a/b/c</code> prefix.
</p>

<p>
Depending on different scenarios, a folder with name <code>vendor</code> might be also viewed
as a special package folder. The following paragraphs will explain when this happens.
</p>

<p>
In Go SDK 1.11, a modules feature was introduced.
A module can be viewed as a collection of packages which have a common root (a package tree).
Each module is associated with an root import path and
<a href="https://semver.org/">a semantic version</a>.
The major version should be contained in the root import path,
execpt the <code>v0</code> or <code>v1</code> major versions.
Modules with different root import paths are viewed as different modules.
</p>

<p>
Go SDK 1.11 also introduced a <code>GO111MODULE</code> environment variable.
Its value can be <code>auto</code>, <code>on</code> and <code>off</code>.
Up to now (Go SDK v1.13), its default value is <code>auto</code>.
By context, different SDK versions interpret <code>auto</code>
as either <code>on</code> or <code>off</code> by different rules.
Please check <a href="https://github.com/golang/go/wiki/Modules">the official wiki</a> for details.
</p>

<p>
If a package is contained within a <code>GOPATH/src</code> directory,
and the modules feature is off, then its import path is the relative path to
either the <code>GOPATH/src</code> directory or the closest <code>vendor</code> folder
which containing the package.
</p>

For example, when the modules feature is off, then for the following hierarchical directory structure,
<ul>
<li>
	the import paths of the two <code>foo</code> packages are both <code>w/foo</code>.
</li>
<li>
	the import paths of the <code>x</code>, <code>y</code> and <code>z</code> packages
	are <code>x</code>, <code>x/y</code> and <code>x/z</code>, respectively.
</li>
</ul>

Note,
<ul>
<li>
	when the file <code>y.go</code> imports a package with import path as <code>w/foo</code>,
	the imported package is the package with folder <code>GOPATH/src/x/y/vendor/w/foo</code>.
</li>
<li>
	when the <code>x.go</code> or <code>z.go</code> file imports a package with import path <code>w/foo</code>,
	the imported package is the package with folder <code>GOPATH/src/x/vendor/w/foo</code>.
</li>
</ul>

<pre class="disable-line-numbers111"><code class="language-go">_ GOPATH
  |_ src
     |_ x
        |_ vendor
        |  |_ w
        |     |_ foo
        |        |_ foo.go    // package foo
        |_ y
        |  |_ vendor
        |  |  |_ w
        |  |     |_ foo
        |  |        |_ foo.go // package foo
        |  |_ y.go            // package y
        |_ z
        |  |_ z.go            // package z
        |_ x.go               // package x
</code></pre>

<p>
</p>

<p>
When the modules feature is on, the root import path of a module is
often (but not required to be) specified in a <code>go.mod</code> file
which is directly contained in the root package folder of the module.
We often use the root import path to identify the module.
The root import path is the common prefix of all packages in the module.
</p>

<p>
Only the <code>vendor</code> folder directly under the root path of a module is viewed as a special folder.
</p>

For example, when the modules feature is on, then in the module identified with <code>example.com/mypkg</code> shown blow,
<ul>
<li>
	the import path of the first <code>foo</code> package is <code>w/foo</code>.
	The <code>MyProject/vendor</code> folder is viewed as a special folder.
</li>
<li>
	the import path of the other  <code>foo</code> package is<code>example.com/mypkg/x/y/vendor/w/foo</code>.
	Note, the <code>MyProject/x/y/vendor</code> folder is viewed as a normal package folder.
</li>
<li>
	the import paths of the <code>x</code>, <code>y</code> and <code>z</code> packages
	are <code>example.com/mypkg/x</code>, <code>example.com/mypkg/x/y</code> and <code>example.com/mypkg/x/z</code>, respectively.
</li>
</ul>

Note, when the <code>x.go</code>, <code>y.go</code> or <code>z.go</code> files import a package with import path <code>w/foo</code>,
the imported package is always the package with folder <code>MyProject/vendor/w/foo</code>.

<pre class="disable-line-numbers111"><code class="language-go">_ MyProject
     |_ go.mod                // module example.com/mypkg
     |_ vendor
     |  |_ w
     |     |_ foo
     |        |_ foo.go       // package foo
     |_ x
        |_ y
        |  |_ vendor
        |  |  |_ w
        |  |     |_ foo
        |  |        |_ foo.go // package foo
        |  |_ y.go            // package y
        |_ z
        |  |_ z.go            // package z
        |_ x.go               // package x
</code></pre>

<p>
</p>

<p>
When one source file in a package imports another package,
we say the importing package depends on the imported package.
</p>

<p>
Go doesn't support circular package dependencies.
If package <code>a</code> depends on package <code>b</code>
and package <code>b</code> depends on package <code>c</code>,
then source files in package <code>c</code> can't import package <code>a</code> and <code>b</code>,
and source files in package <code>b</code> can't import package <code>a</code>.
</p>

<p>
Surely, source files in a package can't, and don't need to, import the package itself.
</p>

<p>
Similar to package dependencies, a module might also depend on some other modules.
The direct module dependecies and their versions are often specified in the <code>go.mod</code> file of the module.
Circular module dependencies are supported, though such scenarios are rare in practice.
</p>

<p>
Later, we will call the packages named with <code>main</code>
and containing <code>main</code> entry functions as <b>program packages</b>,
and call other packages as <b>library packages</b>.
Each Go program should contain one and only one program package.
</p>

<p>
The name of the folder of a package is not required to be the same as the package name.
However, for a library package, it will make package users confused if the name
of the package is different from the name of the folder of the package.
The cause of the confusion is that the default import path of a package is the name of the package
but what is contained in the import path of the package is the folder name of the package.
So please try to make the two names identical for each library package.
</p>

<p>
On the other hand, it is recommended to give each program package folder
a meaningful name other than its package name, <code>main</code>.
</p>
</div>

<a class="anchor" id="init"></a>
<h3>The <code>init</code> Functions</h3>

<p>
There can be multiple functions named as <code>init</code> declared in a package,
even in a source code file.
The functions named as <code>init</code> must have not any
input parameters and return results.
</p>

<p>
Note, at the top package-level block, the <code>init</code> identifier
can only be used in function declarations.
We can't declare package-level variable/constants/types which names are <code>init</code>.
</p>

<p>
At run time, each <code>init</code> function will be (sequentially) invoked once
and only once (before invoking the <code>main</code> entry function).
So the meaning of the <code>init</code> functions are much like the static initializer blocks in Java.
</p>

<div>
Here is a simple example which contains two <code>init</code> functions:

<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func init() {
	fmt.Println("hi,", bob)
}

func main() {
	fmt.Println("bye")
}

func init() {
	fmt.Println("hello,", smith)
}

func titledName(who string) string {
	return "Mr. " + who
}

var bob, smith = titledName("Bob"), titledName("Smith")
</code></pre>

The output of this program:
<pre class="output"><code>hi, Mr. Bob
hello, Mr. Smith
bye
</code></pre>

<p>
</p>

</div>

<a class="anchor" id="initialization-order"></a>
<h3>Resource Initialization Order</h3>

<div>
<p>
At run time, a package will be loaded after all its dependency packages.
Each package will be loaded once and only once.
</p>

<p>
All <code>init</code> functions in all involved packages in a program
will be invoked sequentially.
An <code>init</code> function in an importing package
will be invoked after all the <code>init</code> functions
declared in the dependency packages of the importing package for sure.
All <code>init</code> functions will be invoked
before invoking the <code>main</code> entry function.
</p>

<p>
The invocation order of the <code>init</code> functions in the same source file
is from top to bottom. Go specification recommends, but doesn't require, to invoke
the <code>init</code> functions in different source files of the same package
by the alphabetical order of filenames of their containing source files.
So it is not a good idea to have dependency relations between
two <code>init</code> functions in two different source files.
</p>

<p>
All package-level variables declared in a package are initialized before
any <code>init</code> function declared in the same package is invoked.
</p>

Go runtime will try to initialize package-level variables in a package
by their declaration order, but a package-level variable will be
initialized after all of its depended variables for sure.
For example, in the following code snippet, the initializations the four
package-level variables happen in the order <code>y</code>, <code>z</code>,
<code>x</code>, and <code>w</code>.

<pre class="line-numbers"><code class="language-go">func f() int {
	return z + y
}

func g() int {
	return y/2
}

var (
	w       = x
	x, y, z = f(), 123, g()
)
</code></pre>

<p>
About more detailed rule of the initialization order of package-level variables,
please read the article <a href="evaluation-orders.html#package-level-variables">expression evaluation order</a>.
</p>

</div>

<h3>Full Package Import Forms</h3>

<div>


In fact, the full form of an import declaration is

<pre class="disable-line-numbers111"><code class="language-go">import importname "path/to/package"
</code></pre>

<p>
where <code>importname</code> is optional,
its default value is the name (not the folder name) of the imported package.
</p>

In fact, in the above used import declarations,
the <code>importname</code> portions are all omitted,
for they are identical to the respective package names.
These import declarations are equivalent to the following ones:

<pre class="disable-line-numbers111"><code class="language-go">import fmt "fmt"        // <=> import "fmt"
import rand "math/rand" // <=> import "math/rand"
import time "time"      // <=> import "time"
</code></pre>

<p>
</p>

<p>
If the <code>importname</code> portion presents in an import declaration,
then the prefix tokens used in qualified identifiers must be <code>importname</code>
instead of the name of the imported package.
</p>

<p>
The full import declaration form is not used widely.
However, sometimes we must use it.
For example, if a source file imports two packages with the same name,
to avoid making compiler confused, we must use the full import form
to set a custom <code>importname</code> for at least one package in the two.
</p>

Here is an example of using full import declaration forms.
<pre class="line-numbers"><code class="language-go">package main

import (
	format "fmt"
	random "math/rand"
	"time"
)

func main() {
	random.Seed(time.Now().UnixNano())
	format.Print("A random number: ", random.Uint32(), "\n")

	// The following two lines fail to compile,
	// for "rand" is not identified.
	/*
	rand.Seed(time.Now().UnixNano())
	fmt.Print("A random number: ", rand.Uint32(), "\n")
	*/
}
</code></pre>

Some explanations:
<ul>
<li>
	we must use <code>format</code> and <code>random</code> as the
	prefix token in qualified identifiers, instead of the real package names
	<code>fmt</code> and <code>rand</code>.
</li>
<li>
	<code>Print</code> is another function in the <code>fmt</code> standard package.
	Like <code>Println</code> function calls,
	a <code>Print</code> function call can take an arbitrary number of arguments.
	It will print the string representations of the passed arguments, one by one.
	If two consecutive arguments are both not string values,
	then a space character will be automatically inserted between them in the print result.
</li>
</ul>

<p>
The <code>importname</code> in the full form import declaration can be a dot
(<code>.</code>). Such imports are called dot imports.
To use the exported elements in the packages being dot imported,
the prefix part in qualified identifiers must be omitted.
</p>

Example:
<pre class="line-numbers"><code class="language-go">package main

import (
	. "fmt"
	. "time"
)

func main() {
	Println("Current time:", Now())
}
</code></pre>

<p>
In the above example, <code>Println</code> instead of <code>fmt.Println</code>,
and <code>Now</code> instead of <code>time.Now</code> must be used.
</p>

<p>
Generally, dot imports are not recommended to be used in formal projects.
</p>

<p>
The <code>importname</code> in the full form import declaration can be the blank identifier
(<code>_</code>). Such imports are called anonymous imports (some articles elsewhere also call them blank imports).
The importing source files can't use the exported resources in anonymously imported packages.
The purpose of anonymous imports is to initialize the imported packages
(each of <code>init</code> functions in the anonymously imported packages will be called once).
</p>

In the following example, all <code>init</code> functions declared in
<a href="https://golang.org/pkg/net/http/pprof/">the
<code>net/http/pprof</code> standard package</a> will be called before the
<code>main</code> entry function is called.

<pre class="line-numbers"><code class="language-go">package main

import _ "net/http/pprof"

func main() {
	... // do somethings
}
</code></pre>
</div>

<h3>Each Non-Anonymous Import Must Be Used at Least Once</h3>

<div>
Except anonymous imports, other imports must be used at least once.
For example, the following example fails to compile.
<pre class="line-numbers"><code class="language-go">package main

import (
	"net/http" // error: imported and not used
	. "time"   // error: imported and not used
)

import (
	format "fmt"  // okay: it is used once below
	_ "math/rand" // okay: it is not required to be used
)

func main() {
	format.Println() // use the imported "fmt" package
}
</code></pre>

</div>

<!--
<h3>Package Import Paths</h3>

todo: it is some a chaos currently. It would be good to finish this section at Go 1.12.

<div>
<p>
Before Go SDK 1.11, the <a href="go-sdk.html">official Go tools</a> recommend,
and often require, the folder containing a third-party package to be put in the <code>src</code>
folder under any path specified in the <code>GOPATH</code> environment variable.
The import path of the third-party package is the relative path of
the package folder to the <code>src</code> folder.
The separators in the path must be always <code>/</code> and can't be <code>\</code>.
For example, if the path of a package is <code>OneGoPath/src/a/b/pkg</code>
(or <code>OneGoPath\src\a\b\pkg</code> on Windows),
then its import path is <code>a/b/pkg</code>.
</p>

<p>
Since Go SDK 1.6 (experimented since 1.5), each code package folder
can contain a <code>vendor</code> subfolder, which is used to store
the dependency packages of that code package.
The packages under the <code>vendor</code> subfolder have a higher priorty
in package look-up.
</p>

<p>
Since Go SDK 1.11, the official Go tools start to support modules.
The <code>GOPATH</code> environment variable is still kept
but Go package source code can be put anywhere.
A new environment variable <code>GO111MODULE</code> is used to

Go source code can be put anywhere and <code>GOPATH</code> environment variable is not required

GO111MODULE
</p>

<p>
A standard package has a higher import priority than a third-party package
if their import paths are identical.
So please try to avoid using the import path of a standard package
as the import path of a third-party package.
</p>



</div>
-->







